TGTADM(8) | [FIXME: manual] | TGTADM(8) |
NAME¶
tgtadm - Linux SCSI Target Administration Utility
SYNOPSIS¶
tgtadm [OPTIONS]... [-C --control-port <port>] [-L --lld <driver>] [-o --op <operation>] [-m --mode <mode>] [-t --tid <id>] [-T --targetname <targetname>] [-Y --device-type <type>] [-l --lun <lun>] [-b --backing-store <path>] [-E --bstype <type>] [-I --initiator-address <address>] [-Q --initiator-name <name>] [-n --name <parameter>] [-v --value <value>] [-P --params <param=value[,param=value...]>] [-F --force] [-h --help]
DESCRIPTION¶
tgtadm is used to monitor and modify everything about Linux SCSI target software: targets, volumes, etc.
OPTIONS¶
-C, --control-port <port>
-Y, --device-type <type>
Possible device-types are:
disk : emulate a disk device
tape : emulate a tape reader
ssc : same as tape
cd : emulate a DVD drive
changer : emulate a media changer device
pt : passthrough type to export a /dev/sg device
-E, --bstype <type>
Possible backend types are:
rdwr : Use normal file I/O. This is the default for disk devices
aio : Use Asynchronous I/O
sg : Special backend type for passthrough devices
ssc : Special backend type for tape emulation
--lld <driver> --op new --mode target --tid <id> --targetname <name>
--lld <driver> --op delete --mode target --tid <id>
--lld <driver> --op delete --force --mode target --tid <id>
--lld <driver> --op show --mode target
--lld <driver> --op show --mode target --tid <id>
--lld <driver> --op new --mode logicalunit --tid <id> --lun <lun> --backing-store <path>
--lld <driver> --op delete --mode logicalunit --tid <id> --lun <lun>
--lld <driver> --op bind --mode target --tid <id> --initiator-address <address>
--lld <driver> --op bind --mode target --tid <id> --initiator-name <name>
--lld <driver> --op unbind --mode target --tid <id> --initiator-address <address>
--lld <driver> --op unbind --mode target --tid <id> --initiator-name <name>
--lld <driver> --op update --mode target --tid <id> --name=<parameter> --value=<value>
--lld <driver> --op update --mode target --tid <id> --params parameter=value<,...>
--help
LUN PARAMETERS¶
These parameters are only applicable for "--mode logicalunit".
vendor_id=<string>
product_id=<string>
product_rev=<string>
Example: tgtadm --lld iscsi --mode logicalunit --op update \
--tid <TID> --lun <LUN> \
--params vendor_id=TGTD,product_id=VirtualHD,product_rev=0103
removable=<0|1>
sense_format=<0|1>
online=<0|1>
Devices default to be online when created but can be brought offline using this parameter. Behaviour of offline devices depend on device type. An MMC/DVD device that is offline will report that there is no disk in the unit but the actual MMC/DVD unit itself can still be communicated with. All other device types will fail all I/O with a sense code of Not Ready.
Example: tgtadm --lld iscsi --mode logicalunit --op update \
--tid 1 --lun 1 \
--params removable=1,sense_format=1,online=1
mode_page=<byte-string>
Examples: Create mode page ´2´, subpage 0 and 14 bytes of data. This is Disconnect-Reconnect mode page. tgtadm --mode logicalunit --op update --tid 1 --lun 2 \
--params mode_page=2:0:14:0x80:0x80:0:0xa:0:0:0:0:0:0:0:0:0:0 Create mode page ´10´, subpage 0 and 10 bytes of data. This is Control Extension mode page. tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 \
--params mode_page=10:0:10:2:0:0:0:0:0:0:0:2:0 Create mode page ´0x1c´, subpage 0 and 10 bytes of data. This is Informational Exceptions Control mode page. tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 \
--params mode_page=0x1c:0:10:8:0:0:0:0:0:0:0:0:0
readonly=<0|1>
This parameter only applies to DISK devices.
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 1 \
--params readonly=1
SMC SPECIFIC LUN PARAMETERS¶
These parameters are only applicable for luns that are of type "changer" i.e. the media changer device for a DVD Jukebox or a Virtual Tape Library.
element_type=<1|2|3|4>
Slot types:
1 -> Medium Transport (picker arm)
2 -> Storage Element
3 -> Import/Export Element
4 -> Data Transfer device (CD drive, tape drive, MO drive etc)
address=<1-65535>
start_address=<1-65535>,quantity=<1--65535>
sides=<1|2>
clear_slot=<1>
barcode=<string>
media_home=<string>
To assign a media image file to a storage element slot, you assign "barcode" to be the name of the image file in the "media_home" directory.
Example: How to create a DVD jukebox with eight disk trays and two empty DVD-R disks. # Create a target tgtadm --lld iscsi --mode target --op new --tid 1 --targetname iqn.2007-03:virtual-dvd:`hostname` # Create a DVD drive and give it a nice name # The dvd starts out without a backing store file, i.e. no disk loaded tgtadm --op new --mode logicalunit --tid 1 --lun 1 --device-type cd tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 1 --params vendor_id=STGT_DVD,product_id=DVD101,product_rev=0010,scsi_sn=STGTDVD01,removable=1 # We need a backend store file for the media changer if [ ! -f $HOME/smc ]; then dd if=/dev/zero of=$HOME/smc bs=1k count=1 fi # Create the SMC device and give it a nice name tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 --backing-store $HOME/smc --device-type changer tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params vendor_id=STK,product_id=L700,product_rev=0010,scsi_sn=XYZZY_0,removable=1 # Add a Data Transfer devices (1 drive) tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=4,start_address=1,quantity=1 # Specify that the DVD above (LUN 1) is the data transfer device we created tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=4,address=1,tid=1,lun=1 # Medium Transport Elements (robot arm / picker) tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=1,start_address=16,quantity=1 # define path to virtual media VTL=${HOME}/vtl mkdir -p ${VTL} tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params media_home=${VTL} # Storage Elements - 8 starting at addr 1024 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=2,start_address=1024,quantity=8 # Add ´media´ to slots 1 and 2 and leave the other 6 slots empty # slot 1 # Create empty writeable virtual DVD-R media tgtimg --op new --device-type cd --type dvd+r --file ${VTL}/DISK_001 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=2,address=1024,barcode=DISK_001,sides=1 # slot 2 tgtimg --op new --device-type cd --type dvd+r --file ${VTL}/DISK_002 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=2,address=1025,barcode=DISK_002,sides=1 # Allow ALL initiators to connect to this target tgtadm --lld iscsi --mode target --op bind --tid 1 --initiator-address ALL # Show all our good work. tgtadm --lld iscsi --mode target --op show
PASSTHROUGH DEVICES¶
In addition to device emulation TGTD also supports utilizing existing SG devices on the host and exporting these through a special passthrough device type.
--bstype=sg
--device-type=pt
--backing-store=</dev/sg4>
Example: Make /dev/sg4 available to initiators connecting to TGTD. tgtadm --lld iscsi --op new --mode logicalunit --tid 1 --lun 1 --bstype=sg --device-type=pt --backing-store=/dev/sg4
HEADER DIGEST AND DATA DIGEST¶
Header and data digests can be set on a per target parameter. TGTD supports two modes, None and CRC32C. When the digest is set to None, TDTD will negotiate that digests will not be used, and when CRC32C is set, TGTD will force the connection to use digest.
Viewing the current settings¶
This command is used to view the current settings for header/data digest.
tgtadm --op show --mode target --tid 1
...
HeaderDigest=None
DataDigest=None
...
Setting digest¶
Set header digest to CRC32C: tgtadm --op update --mode target --tid 1 -n HeaderDigest -v CRC32C Set data digest to None: tgtadm --op update --mode target --tid 1 -n DataDigest -v None
CHAP AUTHENTICATION¶
CHAP authentication is supported to require authentication before an initiator is allowed to log in and access devices.
CHAP main-phase authentication is set on the target level. To set up CHAP authentication we first need to create an account and its associated password, then we bind the account to one or more targets.
Setting CHAP on a target¶
These two commands create a user account and binds it to target 1.
tgtadm --lld iscsi --op new --mode account --user ronnie --password password tgtadm --lld iscsi --op bind --mode account --tid 1 --user ronnie
List all accounts¶
This command is used to list all accounts that have been created.
tgtadm --lld iscsi --op show --mode account Account list:
ronnie
Show if a target requires authentication¶
When listing the targets, each target that has authantication enabled will contain a listing of all accoutns bound to that target.
tgtadm --lld iscsi --op show --mode target Target 1: iqn.ronnie.test ... Account information:
ronnie ...
ISCSI PORTALS¶
iSCSI portals can be viewed, added and removed at runtime.
List portals¶
This command is used to list the current iSCSI portals defined on the target:
tgtadm --lld iscsi --op show --mode portal Portal: 10.1.1.101:3260,1 Portal: 127.0.0.1:3260,1
Add portal¶
This command is used to add a portal to the target :
tgtadm --lld iscsi --op new --mode portal --param portal=10.1.1.101:3260
Remove portal¶
This command is used to remove a portal from the target :
tgtadm --lld iscsi --op delete --mode portal --param portal=10.1.1.101:3260
ISCSI CONNECTIONS¶
iSCSI connections can be viewed and forced closed at runtime.
List all active connections for a target¶
This command is used to list the all the active iSCSI connections to the target with connection id, initiator name and ip address for the initiator :
tgtadm --lld iscsi --op show --mode conn --tid 1 Session: 2
Connection: 0
Initiator: iqn.2008-11.org.linux-kvm:
IP Address: 127.0.0.1
Close an existing connection¶
This command is used to close an iSCSI connection. Note that forcibly closing iSCSI connections can lead to data-loss.
tgtadm --lld iscsi --op delete --mode conn --tid 1 --sid 2 --cid 0
ONLINE/OFFLINE STATUS¶
Tgtd LUNs can be in online or offline status. LUNs that are Offline behave slightly different depending on the device type. Offline devices behave as if there is no media available and any operations that access media will fail with an check-condition error.
Devices can not be set to Offline mode while there are "PREVENT ALLOW MEDIUM REMOVAL" locks on the device. Similarly media in Online devices can not be software ejected while there are such locks on the device (the ´eject´ command will fail).
Show Online/Offline status¶
Finding the Online/Offline status of a LUN is done through the tgtd command. If "Prevent removal" is "Yes" this indicates that an application holds a "prevent media removal" lock on the device.
tgtadm --lld iscsi --mode target --op show ...
LUN: 2
Type: cd/dvd
SCSI ID: IET 00010002
SCSI SN: beaf12
Size: 3432 MB, Block size: 1
Online: Yes
Removable media: Yes
Prevent removal: Yes ...
Changing a LUN to Offline¶
A LUN is changed to Offline status using the tgtadm command. When devices are set Offline these devices will behave as if there is no media loaded into the drive.
Change a LUN to become offline. (no disk in the drive)
tgtadm --tid 1 --lun 2 --op update --mode logicalunit -P Online=No
ISNS PARAMETERS¶
iSNS configuration for a target is by using the tgtadm command.
iSNSServerIP
Example: tgtadm --op update --mode sys --name iSNSServerIP --value 192.168.11.133
iSNS
Example: tgtadm --op update --mode sys --name iSNS --value On
iSNSServerPort
Example: tgtadm --op update --mode sys --name iSNSServerPort --value 3205
iSNSAccessControl
Example: tgtadm --op update --mode sys --name iSNSAccessControl --value Off
SEE ALSO¶
tgtd(8), tgt-admin(8), tgtimg(8), tgt-setup-lun(8). http://stgt.sourceforge.net/
REPORTING BUGS¶
Report bugs to <stgt@vger.kernel.org>
05/10/2016 | [FIXME: source] |